home *** CD-ROM | disk | FTP | other *** search
/ PsL Monthly 1993 December / PSL Monthly Shareware CD-ROM (December 1993).iso / prgmming / dos / basic / vol_inf.exe / FHELP.DOC < prev    next >
Encoding:
Text File  |  1993-05-03  |  9.2 KB  |  182 lines
  1. ;
  2. ;DOS, VOLUME Labels
  3.  
  4. =======================================================================
  5.     Copyright (C) Copr. 1990, 1991 1992, 1993 by Sidney J. Kelly
  6.             All Rights Reserved.
  7.             Sidney J. Kelly
  8.             150 Woodhaven Drive
  9.             Pittsburgh, PA 15228
  10.             home phone 412-561-0950 (7pm to 9:30pm EST)
  11.  
  12.      CompuServe   70043,1656
  13. =======================================================================
  14.  
  15.       These routines provides routines to read and set the volume label
  16. on all DOS formatted disks.  No ON ERROR necessary.  This routine has
  17. been reworked to overwrite Norton's Safe Format volume labels, which DOS
  18. version 5.00 can't handle, but DOS version 3.x can.
  19.  
  20.         This library will work in PDS 7.x but will not work in the QBX
  21. environment because it uses NEAR strings.  You must modify the string output
  22. routines to use LIBRARY calls to make it work inside QBX.EXE.
  23. Jim Mack has released some routines for PDS on COMPUSERVE MSSYS
  24. TRIMS.ASM.  It shows how to pass far strings inside PDS.
  25.  
  26.  =================================================================
  27.  
  28.           QBASIC-MASM Interface Theory:
  29.           Generally QBASIC only keeps simple variables, (INT,
  30. LONGINT, SINGLE and DOUBLE, and STRINGS) in DGROUP.  Arrays and
  31. TYPE records are usually kept outside DGROUP, with only the
  32. STRING Descriptor or the undocumented Array descriptor kept in
  33. DGROUP.  Thus, the library routines assume that all information
  34. passed from simple variables is information about a near (DGROUP)
  35. address.  If we pass simple integers to MASM routines, and don't
  36. care to have MASM change those variables, we use BYVAL to send
  37. the information to MASM.  BYVAL speeds up variable access by a
  38. factor of two.  If we want to have MASM send information back
  39. about multiple variables, we must pass the address information
  40. for the variables without using BYVAL.  If we use arrays, we must
  41. use a combination of BYVAL & VARSEG and BYVAL & VARPTR to get the
  42. information we need to manipulate the information inside the
  43. arrays.  VARSEG and VARPTR are necessary because there is a very
  44. great chance that the arrays will be stored as far data (i.e. not stored in DGROUP).  If you must get an array in DGROUP, put the
  45. array in COMMON.
  46.           Text strings are sent by QBASIC as near address
  47. (relative to DS and DGROUP).  The fist value in the descriptor is
  48. the length of the string.  The second value is the offset address
  49. inside DGROUP.  Fixed length strings and TYPE record strings are
  50. not referenced with string descriptors.  For that reason, I don't
  51. allow such strings as variables in my routines.
  52.           PDS/QBX Version 7.x stores strings in FAR DATA, outside
  53. DGROUP.  Special routines are offered in the programmer's package
  54. to find address and length of far strings.  
  55. You must use the following library routines included inside the QBX environment.
  56.  
  57.           Use the following library calls:
  58.           EXTRN StringAddress:FAR
  59.           EXTRN StringLength:FAR
  60.  
  61. How to use StringLength   (must clear direction flag CLD):
  62. Basic program must pass address of string descriptor on stack
  63. Push    StringDescriptor  ; push it back on stack
  64. call StringLength         ; call routine
  65. length returned in AX
  66.  
  67. How to use StringAddress (must clear direction flag CLD):
  68. Basic program must pass address of string descriptor on stack
  69.  
  70. Push    StringDescriptor   ; push it back on stack
  71. call StringAddress         ; call routine
  72. address returned in DX:AX  ; DX has segment address, AX has
  73.                            ; offset
  74.  
  75.           QBASIC requires that MASM preserve BP, SI, DI, DS, and
  76. keep the direction flag clear (CLD).  All these routines do this.
  77. You will note that MICROSOFT'S CALL INTERRUPT routines do not
  78. save BP (apparently to give you access to some EGA VGA palette
  79. and character font selection routines in the BIOS), and thus will
  80. crash if a critical error occurs.  MICROSOFT offers a replacement
  81. routine that overcomes this error by preventing any change to BP.
  82. You should get it if you don't already have it.  QBX requires that ES
  83. be preserved for FAR strings.  THIS HAS NOT BEEN DONE!
  84.           The choice of defining MASM routines as SUB's or
  85. FUNCTION's depends on whether you want to get information from
  86. MASM in DX:AX (the format for FUNCTIONs), or if the MASM routine
  87. either sends back no information or more than one variable (the
  88. format for SUBs).  For simple one variable routines when MASM is
  89. just returning a value, use FUNCTIONs.  To use such functions
  90. inside QBASIC you must either assign the value of the function to
  91. a QBASIC variable or use 1) IF ... THEN statements (C style), or
  92. 2) PRINT statements.  For everything else use SUBS.
  93.           Note due to an error in the QBASIC text parser, always
  94. use the CALL keyword to call the library routines if there is any
  95. chance that you will use a colon as a separator on a line AND the
  96. library routine does not take any parameters.  Without the CALL
  97. keyword, the QBASIC parser assumes that the routine name followed
  98. by a colon is intended as a line label, and not as a SUB name.
  99. You must use CALL if you will use a SUB that does not need any
  100. parameters and will follow that SUB name by a colon.
  101.           MASM Theory:
  102.           The MASM routines were designed to be compiled with MS
  103. QUICK ASSEMBLER, using simplified segment names.  They should
  104. compile with MS MASM 5.1 and above.  The DOSSEG keyword might not
  105. be supported by your version of MASM, so use the MASM keyword
  106. that arranges the segments in DOS order, rather than ALPHA order.
  107. If you use TASM with QUIRKS and MASM51  you should be able to
  108. compile these programs with TASM.  The @@, @f, @b are local 
  109. labels used so I can skip ahead without having to think up 
  110. unique names.  Don't use @@, @f,@b inside MASM Macros, 
  111. use LOCAL alphanumeric names instead.  MASM too easily can 
  112. lose track of which local label you mean.
  113.           The simplified directives really save time when you
  114. have to identify variables on the stack, and push and pop
  115. variables.  I use the full PROC function and the regular PROC keywords interchangeably.  Full PROC format is not necessary when
  116. there is no need to address variables on the stack (i.e. no need
  117. to change BP to address the stack) and the QBASIC routine is
  118. described as a FUNCTION or a SUB that does not take or return
  119. parameters..
  120.           The EVEN directive is used to word align loops for
  121. 80286 and 80386 machines.  EVEN inserts NOPS as necessary to word
  122. align loops.  The QBASIC BYVAL directive is used to get
  123. information directly from QBASIC without having to use [BX] or
  124. [SI] to fish out the correct information.  To allow for
  125. compatibility with the 8088 chip, shifts rather than MULs are
  126. used for speed.  I use .code to store most of my variables to
  127. save space in DGROUP, which is comparatively tiny and easily
  128. filed with string data.
  129.           To program in OS/2 code segment variables are
  130. "verbotten", and you must use local variables on the stack.  I
  131. don't have access to the OS/2 DOS compatibility box, so I don't
  132. know how these routines would work under OS/2.  I am certain that
  133. none of these routines would work smoothly under protected mode
  134. because they often access the BIOS or the hardware.
  135.  
  136. What's available:
  137.  
  138.     DOSBASIC ZIP - (released 12-19-90).  The first draft
  139. of many of these routines.  The current version is much faster and does
  140. more.  Uploaded on GENIE and COMPUSERVE
  141.  
  142.         VIDBASIC (released 11-29-90)
  143.     - A selection of text mode video routines.  Bannerware.
  144. The library allows the user to select, move, switch, change, save,
  145. restore, draw boxes, and write with lightening speed.  MASM .ASM code,
  146. .OBJ, and a demo routine with source is included.  Uploaded by author on
  147. GENIE and COMPUSERVE.
  148.  
  149.         KEYBASIC - (released 12-14-90)
  150.     A selection of Microsoft Compatible Mouse and
  151. Keyboard utilities.  Text mode mouse utilities.  Fast mouse utilities.
  152. Turn off CONTROL-BREAK so you can use LINE INPUT$ without error if user
  153. pushes the Control-Break key.  Bannerware. MASM .ASM code, .OBJ, and a
  154. demo routine with source is included.  Uploaded by author on GENIE and
  155. COMPUSERVE.
  156.  
  157.     PDS-VID  ZIP     (released 03-01-91)
  158.     Shows how to use far strings inside QBX/PDS.  Gives all the
  159. proper library call format.  Uploaded on COMPUSERVE.
  160.  
  161.     EDIT-QB  ZIP     (released 05-23-91)
  162.     A fast on screen text line editor.  Should be compatible with
  163. all displays because it uses bios calls to display characters.
  164.  
  165.     VERT-LIB ZIP    (released 12-31-91)
  166.     with update VERT-L1  ZIP (04-27-92).  This shows a complex
  167. shell for QBASIC near strings.  Complete display control, PULL DOWN
  168. and POP UP menus, and simple help box.  Works with MOUSE or keyboard.
  169. Full source MASM and QBASIC included.
  170.  
  171.     QB-EQUIP  ZIP    (released 12-31-92)
  172.         A fast set of hardware ID routines with MASM source. Bannerware.
  173. Uploaded on COMPUSERVE.
  174.  
  175.         As always, constructive criticism is desired.  These libraries
  176. were released as Bannerware (you can use the .OBJ files) but you can't
  177. sell the source) to encourage a sharing of ideas.  If you have
  178. something to say, I welcome your comments.  With application programs
  179. there appears to be a significant and speedy exchange of ideas,
  180. programmers, on the other hand, seem to move at a much slower pace, with
  181. Jim Mack being the notable exception.
  182.